Shareware Grab Bag/Shareware Grab Bag.iso/007/d86v223.arc/MAIN.DOC

Text File | 1987-05-04 | 12KB | 287 lines

---MAIN.DOC---

Invoking the D86 Debugger

D86 is the screen-oriented symbolic debugger used with programs
assembled under the assembler A86.   D86 runs on an MS-DOS
system, with an IBM-compatible monochrome or color-graphics video
interface.

You invoke D86 by issuing the command

   D86 [-V] [progname [command-tail]]

where progname.SYM and progname.COM are the symbols and output
files of the A86 assembler.  In other words, you simply provide
the program invocation line, with the word D86 appended to the
start.

It is not necessary for progname.SYM to be present.  If it is
not, then the debugger simply comes up with no user symbols
defined.

You can also invoke D86 with no progname.  The debugger comes up
with no program loaded, allowing you to simply poke around the
machine.

If you don't see symbols, or you don't see your program in
memory, then D86 had some problem loading your files.  The later,
product-quality version of D86 will tell you this explicitly, but
right now you simply have to deduce it.

The -V option can be used if you have both a monochrome and a
color monitor. If you specify -V, the debugger will appear on
whichever screen is NOT currently selected.  This allows you to
see both the debugger output and the program output at the same
time.


The D86 Screen Display

When D86 starts up, it generates a full-screen display, and
awaits your debugger commands.

In the top part of the screen is a symbolic disassembly of the
A86 program, with the screen cursor positioned next to the
instruction pointed to by the 8086 instruction pointer.

In the lower right corner is a fixed display of the complete 8086
register set.

At the top of the second column of the register-set display is a
display of the 8086 flags.  Each flag displays as blank if the
flags is off; and a lower-case letter if the flag is on:
          "o" for overflow,
          "d" for direction,
          "i" for interrupts enabled,
          "s" for sign,
          "z" for zero,
          "a" for auxiliary carry,
          "p" for parity even, and
          "c" for carry.

Across the bottom line of the screen is a display of the contents
of the user stack.  The display begins next to the SP register
value, with the number of elements on the stack.  (The stack is
assumed to have 0 elements when SP is at its original value,
0FFFE). The number of elements is followed by a colon, followed
by as many of the top stack elements as fits on the line.  The
initial display will have zero elements; nothing is yet on the
stack.

To the right of the registers are 6 lines, numbered 1 through 6.
On these lines, you can generate windows into 8086 memory,
displaying bytes, words, or ASCII text in a variety of formats.
The windows can be located either at absolute memory locations,
or be pointed to by any of the 8086 registers.  The commands you
issue to generate these windows are described in the next
section.



D86 Commands

There are 5 kinds of activities you perform in D86:

   1. Issuing assembly-language commands for immediate execution
   2. Issuing debugger commands via lines that begin with a
      single letter
   3. Issuing debugger commands via the function and edit keys on
      your keyboard
   4. Setting up windows displaying memory
   5. Issuing assembly-language commands to enter into memory
      (PatchMem)



Immediate Assembly-Language Commands

A primary part of the D86 command language is the A86 assembly
language. With it, you can jump to different areas of your
program, set your registers, perform arithmetic, and call any of
the procedures of your program.  Simply type in any legal A86
instruction, and it will be executed immediately.

JMP and RET instructions cause the program counter (and thus also
the disassembly) to move to the indicated destination.  CALL
instructions cause the entire procedure to be executed.

WARNING: The immediate-execution feature is a little tricky if
  you are in a multi-segment program, of if you jump to exotic
  parts of the 86 memory space (i.e., into MSDOS, ROM, video
  memory, or the interrupts table). This is because D86 needs a
  buffer in which to put the immediate-execution command.  The
  buffer should be in your program's CS segment, so that commands
  such as jumps and near calls execute correctly.  So D86 must
  always search in CS for a satisfactory buffer.  Here is how
  D86 finds it:

  1. If you declare a label D86_BUFFER, pointing to a buffer
     within your program, then D86 will use that buffer as the
     offset for its immediate instruction.

  2. If not, then if the program's CS register is the same as its
     SS register, D86 will use (SP-300) as its immediate buffer.
     Thus, our stack should have plenty of room (a good practice
     in general).

  3. As a last resort, D86 uses offset 00E0, which points to the
     last 32 bytes of the Program Segment Prefix (PSP).  In that
     case, if you were to issue an immediate command that read
     from a disk file, you would be in trouble, because the disk-
     read operation clobbers the PSP, and the command would then
     not be trapped back to the debugger.

  In cases 1 and 3 above, the segment containing the buffer is
  the program's CS segment, unless that is out of range (below
  the program's original CS, or above the top of available
  program memory).  If the program CS is out of range, the
  program's original CS is used instead.  In that case, immediate
  instructions such JMP, RET, and CALL will not work correctly.

  Note that the above caveats to not apply to single-stepping.



Entering Instructions Into Memory

D86 allows you to alter 8086 memory in two ways: first, you can
issue immediate assembly language commands which, when executed,
store values in memory.  The other method is to enter a special
mode, in which you enter instructions directly into 8086 memory.

You enter this mode by typing the F7 (PatchMem) key. The screen
cursor jumps from the left edge of the line at the current
program counter, into the middle of the line where the
instruction is.  You start typing over the instruction, to signal
that you are clobbering the instruction that was there.  If you
did not intend to enter this mode, you can backspace back to the
start of the instruction, and type a carriage-return.

Each line you type in is checked for errors.  If there was an
error, a message is displayed, the cursor remains at the same
location, and you try again. If there was no error, the cursor
moves beyond the newly-assembled line, and you can type in
another line.

To exit the memory-programming mode, you type any of the control-
key commands at the beginning of the line.  (Type carriage-return
if you don't want any actions to be performed.)


Entering Data into 8086 Memory

You can deposit data into the 8086 memory space by using the
programming mode described in the above section.  Simply enter DB
and/or DW statements instead of instructions.  Note that ASCII
strings can be entered with the DB instruction; and that arrays
can be initialized via the DUP operator in a DB or DW statement.


Adding Symbols to a Program

Patch-mode also allows you to do something that you cannot do in
immediate-execution mode: add symbols to the program.  You can do
so by either:

   1. Typing in a new symbol-name, followed by a colon; or
   2. Typing in an EQU directive.

There are several uses for this.  First, you might want to create
an abbreviation, by equating a short name to a long one, or to a
hard-to-remember constant value.  Second, you might want to
"reverse engineer" a program for which you have a .COM file, but
not the A86 source code.  Each time you add a label, the
disassembly becomes more readable.  Third, you might want to
label code which you have added in patch-mode.

Starting with V2.16, forward referencing is now allowed when you
are in patch mode.  You must be careful, however, to resolve any
forward references you have made.  In particular, you will cause
the assembler to become very confused (and possibly trash random
memory) if you overwrite a forward reference with some other code
before you resolve the reference.  So don't!


D86 Control-Key Functions

D86 has a set of functions invoked by single keys, which can be
invoked any time D86 is awaiting the beginning of an assembly-
language command.

F1           Single-step the current instruction.  If the
             instruction is a call, go into the procedure to
             single-step it.  If you want the entire procedure
             executed on a single keystroke, use the F2 key.

F2           Procedure-step: start program, trapping at the
             instruction following the current one.  This is used
             for executing a procedure call all at once; for
             breaking out of a loop; and for executing a repeated
             string operation all at once.

F3           Repeat the last typed-in assembly language or
             debugger command

F4           Start the program, setting a trap at the destination
             of the conditional-jump instruction currently
             pointed to.  If we are not pointing to a conditional
             jump, then we single-step.

F6           Start the program, setting a trap at the address on
             top of the stack (hopefully a procedure-return
             address).

F7           Enter the previously-described Patch Memory mode.

Shift-F7     Mark the current CS:IP memory location, for use by
             a following F debugger line command.  F can either
             return to this location, or find memory bytes that
             match the ones at this location.

Alt-F9       If you have a Color video board, your debugger
             display may become corrupted by the program's
             console output.  If it does, press Alt-F9 to
             eliminate the corruption.  This key exists only
             temporarily; on later versions of D86, the
             corruption will be corrected automatically.

F10          When you are in Help-Mode, this key gives you
             alternate help windows in some contexts.  When you
             are not in Help-Mode, this key toggles though the
             display windows: in this preliminary debugger, that
             is just the sign-on message, the floating-point
             display if you have a chip, and a blank window.

Down-arrow   Jump to the instruction following the current one,
             without executing the current instruction.

Up arrow     "Up": decrement the current program counter.

Pg Dn        Jump to the next disassembly page, without executing.

Home         Jump to location 0100 in the current code segment.
             In most .COM programs, this will be the start of the
             program.  NOTE that no other re-initializations take
             place with this command.  If you wish to completely
             reinitialize your program, you should exit and
             reenter the debugger.


Alternate Control-Key Assignments For Non-IBM Computers

Some of the computers for which D86 is programmed have alternate
key mappings, to accommodate the differing keyboard layout.

The Wang PC toggles help via the HELP key instead of the Alt-F10
key.

The TI-PC toggles help via the F11 key.  It jumps to the next
disassembly page via Alt-downarrow instead of PgDn.

The Sanyo toggles help via CTRL-PF5 instead of Alt-F10.  It
restores a trashed screen via Ctrl-Shift-PF4 instead of Alt-F9.
It marks the current CS:IP location via Strl-7 instead of Shift-
F7.